home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / raytrace / rayshade / graphtal.lzh / Graphtal.Amiga / graphtal.cat < prev    next >
Text File  |  1992-11-20  |  31KB  |  1,057 lines
  1.  
  2.  
  3.  
  4. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      graphtal - L-system generation program
  10.  
  11.  
  12. SYNOPSIS
  13.      graphtal [options] [file]
  14.  
  15.  
  16. DESCRIPTION
  17.      graphtal is a tool for manipulating  spT0L-systems  (context
  18.      free, table oriented L-systems with stochastic productions).
  19.      graphtal reads a file containing an L-system description and
  20.      starts  the interpretation. In addition, graphtal is able to
  21.      interpret the result graphically, producing different  kinds
  22.      of output.
  23.  
  24.      The main reference for the program is the book  _T_h_e  _V_i_r_t_u_a_l
  25.      _L_a_b_o_r_a_t_o_r_y:  _T_h_e _A_l_g_o_r_i_t_h_m_i_c _B_e_a_u_t_y _o_f _P_l_a_n_t_s by P. Prusink-
  26.      iewicz and A. Lindenmayer. The language used in graphtal  is
  27.      different  from  the  one  in the book and will be described
  28.      completely in this document.
  29.  
  30.      The following sections describe how  to  run  graphtal,  the
  31.      input format accepted and turtle commands implemented.
  32.  
  33.  
  34. NOTATION
  35.      o+  [thing] Optional item.
  36.      o+  <Thing> Production.
  37.      o+   Thing  Number or String.
  38.      o+  (thing) Default value(s).
  39.      o+   thing  Keyword.
  40.  
  41.  
  42. SECTION 1: RUNNING GRAPHTAL
  43.   OPTIONS
  44.      Command line options override  the  settings  in  the  input
  45.      file.  The following options are accepted:
  46.  
  47.      -O outfile
  48.           Sets the output file name.
  49.  
  50.      -R xres yres
  51.           Render at given resolution. The default is set to (400,
  52.           400).
  53.  
  54.      -E x y z
  55.           Set eyepoint vector. The default is set to (0 1 0).
  56.  
  57.      -L x y z
  58.           Set lookat vector. The default is set to (0 0 0).
  59.  
  60.  
  61.  
  62.  
  63.                   Last change: October 27, 1992                 1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  71.  
  72.  
  73.  
  74.      -U x y z
  75.           Set up vector.  The default is set to (0 0 1).
  76.  
  77.      -f angle
  78.           Set field of view. The default is set to (45)
  79.  
  80.      -Dname
  81.           Define name as 1 (cpp option).
  82.  
  83.      -Dname=def
  84.           Define name as "def" (cpp option).
  85.  
  86.      -d drivername
  87.           Set the output device driver.  The  default  driver  is
  88.           (x11simple).
  89.  
  90.           Drivers included:
  91.              no        No turtle interpretation.
  92.              example   Example driver.
  93.              bbox      Calculate bounding box and viewing
  94.                        parameters.
  95.              rayshade  Rayshade driver.
  96.              x11simple Simple line drawing driver for X11.
  97.              x11wire   Wire frame driver for X11.
  98.              flat      Simple z-buffering.
  99.  
  100.      -c   Toggle cone spheres generation.  If  cone  spheres  are
  101.           enabled,  line segments are connected with spheres. The
  102.           default is (no cone sphere generation).
  103.  
  104.      -s   Show the defined hulls. The default is set to (no).
  105.  
  106.      -v   Verbose output. The default is set to (not verbose).
  107.  
  108.      -q   Run quietly. The default is set to (don't be quiet).
  109.  
  110.      -l   Print L-system definition. The default is set to (don't
  111.           print it).
  112.  
  113.      -p   Print resulting module string. The default  is  set  to
  114.           (don't print the modules).
  115.  
  116.      -e   Erase module after turtle interpretation.  The  default
  117.           is set to (don't erase).
  118.  
  119.      -h   Help: print the command line options.
  120.  
  121.  
  122. SECTION 2: LANGUAGE DESCRIPTION
  123.      graphtal accepts a grammar  describing  spT0L-systems,  with
  124.      the following features:
  125.  
  126.  
  127.  
  128.  
  129.                   Last change: October 27, 1992                 2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  137.  
  138.  
  139.  
  140.           o+  D0L-systems (DOL),
  141.           o+  tables of productions (TOL),
  142.           o+  productions with parameters (pTOL),
  143.           o+  stochastically applied productions (spTOL),
  144.           o+  global and local constants,
  145.           o+  hull definitions (turtle interpretation with regard to
  146.              these hulls),
  147.           o+  production parameters may be strings or real values.
  148.  
  149.      All these features may be freely combined.
  150.  
  151.   CASE SENSITIVE
  152.      graphtal is case sensitive.
  153.  
  154.   NAMES
  155.      Two types of names are accepted: _m_o_d_u_l_e names, and  _v_a_r_i_a_b_l_e
  156.      names.  Variable  names  follow the rules for C identifiers:
  157.      arbitrarily long strings chosen from the character  set  [A-
  158.      Za-z_0-9],  with digits disallowed as the leading character.
  159.      Module names are variable names or one of the following spe-
  160.      cial characters:
  161.  
  162.            + - ^ & \ / | $ [ ] { . } ~ %.
  163.  
  164.   EXPRESSIONS
  165.      _E_x_p_r_e_s_s_i_o_n_s generally follow the  rules  of  C  expressions.
  166.      Variable  names,  string  constants  and  numeric values are
  167.      operands.
  168.  
  169.      The predefined variables and constants:
  170.  
  171.      - constants
  172.           M_PI, M_PI_2,  M_PI_4,  M_E,  M_SQRT2,  M_LN2,  M_LN10,
  173.           true, false
  174.  
  175.      - variables
  176.           _t_u_r_t_l_e_x, _t_u_r_t_l_e_y, _t_u_r_t_l_e_z (current position of turtle)
  177.  
  178.      and the operators and functions:
  179.  
  180.      - logical operators:
  181.           !, ||, &&, ==, !=, <, <=, >, >=
  182.  
  183.      - arithmetic operators:
  184.           :: (scope operator), +, - (unary and binary), *,  /,  %
  185.           (remainder), ** (exponentiation), ^ (exponentiation)
  186.  
  187.      - functions
  188.           _s_i_n, _c_o_s, _t_a_n, _a_s_i_n, _a_c_o_s, _a_t_a_n, _a_b_s, _s_q_r_t,  _e_x_p,  _l_o_g,
  189.           _l_o_g_1_0,  _r_a_n_d  (generate  a  random  number in the range
  190.           (0,1) ), _g_a_u_s_s (generate a gaussian  random  number  in
  191.           the range (0,1) ), _i_f (if(a,b,c) <=> if (a) b else c)
  192.  
  193.  
  194.  
  195.                   Last change: October 27, 1992                 3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  203.  
  204.  
  205.  
  206.      graphtal tries to simplify  each  expression  by  evaluating
  207.      constant subterms. For example the expression
  208.  
  209.           sqrt(2*2)*rand() is reduced to 2*rand().
  210.  
  211.      Reals  and  strings  may  be   combined   and   string/real,
  212.      real/string  promotion  is done at evaluation time according
  213.      to the following rules:
  214.  
  215.      Operators:
  216.      - _r_e_a_l/_r_e_a_l No promotion necessary.
  217.  
  218.      - _r_e_a_l/_s_t_r_i_n_g
  219.           Convert the second argument to real if possible, other-
  220.           wise   convert   the   real   argument   to  string  ->
  221.           string/string calculations are applied.
  222.  
  223.      - _s_t_r_i_n_g/_r_e_a_l
  224.           Convert  the  second  argument   to   string   and   do
  225.           string/string calculations.
  226.  
  227.      - _s_t_r_i_n_g/_s_t_r_i_n_g
  228.           Logical operators do string comparison.  The arithmetic
  229.           operator + is defined as string concatenation.  For the
  230.           other arithmetic operators the arguments are  converted
  231.           to  real  and real/real calculation is done. If this is
  232.           impossible, an error occurs.
  233.  
  234.      Functions:
  235.        All the function arguments are converted to real. If this
  236.        is impossible, an error occurs.
  237.  
  238.  
  239.   LSYSTEM
  240.      graphtal accepts a single file in the format described below
  241.      from  standard  input or a given file. The L-system descrip-
  242.      tion is parsed and the tables of productions are applied  to
  243.      the  _a_x_i_o_m  as  specified within the _a_t_t_r_i_b_u_t_e_s _s_e_c_t_i_o_n. The
  244.      resulting module string controls a 3d turtle and produces an
  245.      image. In EBNF an L-system looks like this:
  246.  
  247.      LSystem:
  248.           lsystem Name [ <GlobalConstants> ] [ <Hulls> ]
  249.                <Tables> <Attributes> ;
  250.  
  251.      GlobalConstants:
  252.           <ConstantsDef>
  253.  
  254.  
  255.   CONSTANTS
  256.      An L-system description file may contain any number of  con-
  257.      stants.  The scope of a local constant is the table where it
  258.  
  259.  
  260.  
  261.                   Last change: October 27, 1992                 4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  269.  
  270.  
  271.  
  272.      was defined, whereas the scope of  global  constant  is  the
  273.      whole L-system description. Because local constants may hide
  274.      the name of a globally defined constant, the scope  operator
  275.      (::) may used to have explicitly access to global scope.
  276.  
  277.      Example:
  278.           lsystem test;
  279.           /* definition of global constants */
  280.           const a = 5*sin(M_PI);
  281.                 b = a*a;
  282.  
  283.           table one {
  284.             /* local constant definition within a table, */
  285.             /* access to global constant via scope operator */
  286.             const a = ::a;
  287.             ...
  288.           };
  289.  
  290.  
  291.      ConstantsDef:
  292.           const <Constants>
  293.  
  294.      Constants:
  295.             <Constant>
  296.           | <Constants> <Constant>
  297.  
  298.      Constant:
  299.           Name = <expression> ;
  300.  
  301.   HULLS
  302.      Hulls are a special feature of graphtal, which allows a glo-
  303.      bal  control of growth in the interpretation process. A hull
  304.      consists of primitives . Any number of hulls may be defined.
  305.      If a hull is activated, the turtle moves with regard to that
  306.      hull, i.e. when the current path of the turtle intersects  a
  307.      hull  primitives,  the  interpretation is stopped and one of
  308.      two possible procedures is executed:
  309.  
  310.           o+  reflect the turtle on the surface
  311.              we hit (regarding a reflectance factor)
  312.           o+  cut the current branch
  313.  
  314.      The definition of primitives has  been  adapted  from  Craig
  315.      Kolbs  rayshade.  This  allows  a  user  to  include already
  316.      defined objects into the L-system description  file.  As  an
  317.      example the definition of a house could affect the growth of
  318.      a tree in the way, that  the  tree  may  not  penetrate  the
  319.      house.
  320.  
  321.      Example:
  322.           hull aHull {
  323.             plane 0 0 0 0 0 1
  324.  
  325.  
  326.  
  327.                   Last change: October 27, 1992                 5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  335.  
  336.  
  337.  
  338.             cylinder 1 0 0 0  /* unit cylinder */
  339.                        0 0 1
  340.               scale 1 1 2
  341.               translate 0 0 5
  342.           };
  343.  
  344.  
  345.      Hulls:
  346.             <Hull>
  347.           | <Hulls> <Hull>
  348.  
  349.      Hull:
  350.           hull Name { <Primitives> } ;
  351.  
  352.      Primitives:
  353.             <Primitive> [<Transforms>]
  354.           | <Primitives> <Primitive> [<Transforms>]
  355.  
  356.      Primitive:
  357.             sphere   Radius Xpos Ypos Zpos
  358.           | triangle Xv1 Yv1 Zv1 Xv1 Yv1 Zv1 Xv1 Yv1 Zv1
  359.           | plane    Xpos Ypos Zpos Xnorm Ynorm Znorm
  360.           | cylinder Radius Xbase Ybase Zbase Xapex Yapex Zapex
  361.           | cone     Rbase Xbase Ybase Zbase
  362.                      Rapex Xapex Yapex Zapex
  363.  
  364.      Transforms:
  365.           <Transform>
  366.           <Transforms> <Transform>
  367.  
  368.      Transform:
  369.           translate  Xtrans Ytrans Ztrans
  370.           scale      Xscale Yscale Zscale
  371.           rotate     Xaxis Yaxis Zaxis Degrees
  372.           transform  A  B  C
  373.                      D  E  F
  374.                      G  H  I
  375.                     [Xt Yt Zt]
  376.  
  377.      Arguments for the primitives and transformations are numeric
  378.      values and constants.
  379.  
  380.  
  381.   TABLES
  382.      A table is a collection of productions. Any number of tables
  383.      may  be  defined within a description file.  Designing an L-
  384.      system in a table oriented manner, allows the user to  modu-
  385.      larize  the productions. For instance the L-system of a tree
  386.      could consist of  two  tables,  one  for  the  branches  and
  387.      another  for  the  leafs.   Please  look at the examples for
  388.      further details.
  389.  
  390.  
  391.  
  392.  
  393.                   Last change: October 27, 1992                 6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  401.  
  402.  
  403.  
  404.      Tables:
  405.             <Table>
  406.           | <Tables> <Table>
  407.  
  408.      Table:
  409.           table Name { <Constants> <Productions> } ;
  410.  
  411.   PRODUCTIONS
  412.      graphtal allows the definition of productions with parameter
  413.      and  probabilities.  All  the  productions are context free.
  414.      It's better to show some examples  instead  of  giving  long
  415.      explanations:
  416.  
  417.      A production in a D0L-System:
  418.  
  419.           MatchingModule -> any any any;
  420.  
  421.      A production with parameters and condition:
  422.  
  423.           F(l) : l > 0.5 -> F(l2) A(l+1);
  424.  
  425.      An "empty" production (eat the module):
  426.  
  427.           Leaf(season) : season == "winter" -> ;
  428.  
  429.      A stochastic production:
  430.  
  431.           Branch(l) -> (0.2) F(l)
  432.                     -> (0.5) F(l/2) F(l/2)
  433.                     -> (0.3) ;
  434.  
  435.      And now the detailed EBNF for <Productions>:
  436.  
  437.      Productions:
  438.             <Production>
  439.           | <Productions> <Production>
  440.  
  441.      Production:
  442.           <Predecessor> [ <Condition> ] <Successors> ;
  443.  
  444.      Predecessor:
  445.           Name [ <Arguments> ]
  446.  
  447.      Arguments:
  448.           ( <Parameters> )
  449.  
  450.      Parameters:
  451.             Name
  452.           | <Parameters> , Name
  453.  
  454.      Condition:
  455.           : <Expression>
  456.  
  457.  
  458.  
  459.                   Last change: October 27, 1992                 7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  467.  
  468.  
  469.  
  470.      Successors:
  471.             <Successor>
  472.           | <Successors> <Successor>
  473.  
  474.      Successor:
  475.           -> [ <Probability> ] [ <Modules> ]
  476.  
  477.      Modules:
  478.             <Module>
  479.           | <Modules> <Module>
  480.  
  481.      Module:
  482.           Name [ ( <ExpressionList> ) ]
  483.  
  484.      Probability:
  485.           Number
  486.  
  487.      ExpressionList:
  488.             <Expression>
  489.           | <ExpressionList> , <Expression>
  490.  
  491.  
  492.   ATTRIBUTES
  493.      In the attributes section of the L-system description  file,
  494.      all  the parameters are set, which affect the interpretation
  495.      process. The _a_x_i_o_m and  _d_e_r_i_v_a_t_i_o_n  attributes  have  to  be
  496.      declared. Here's the list of attributes:
  497.  
  498.      Attributes:
  499.           attributes { <AttributesList> } ;
  500.  
  501.      AttributesList:
  502.             derivation <Derivations> ;
  503.           | axiom <Modules> ;
  504.           | roll <Expression> ;
  505.           | turn <Expression> ;
  506.           | pitch <Expression> ;
  507.           | angle <Expression> ;
  508.           | forward <Expression> ;
  509.           | randomize [ <Expression> ] ;
  510.           | tropism <Expression> , <Expression> , <Expression> ;
  511.           | weight <Expression> ;
  512.           | eye <Expression> , <Expression> , <Expression> ;
  513.           | lookat <Expression> , <Expression> , <Expression> ;
  514.           | up <Expression> , <Expression> , <Expression> ;
  515.           | fov <Expression> ;
  516.           | coneres Number ;
  517.           | sphereres Number ;
  518.  
  519.      Derivations:
  520.             Name [ <Steps> ]
  521.           | <Derivations> , Name [ <Steps> ]
  522.  
  523.  
  524.  
  525.                   Last change: October 27, 1992                 8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  533.  
  534.  
  535.  
  536.      Steps:
  537.             ( <Expression> )
  538.           | ( infinity )
  539.  
  540.  
  541.   DERIVATION
  542.      The derivation attributes specifies the tables to be applied
  543.      to  the  axiom. Global constants may be used in step defini-
  544.      tions.  Examples:
  545.  
  546.      Apply table1 once and table2 10 times to the axiom:
  547.  
  548.           derivation table1, table2(10);
  549.  
  550.      Apply table1 once to the axiom and table2 as long a  produc-
  551.      tion of the table matches any module in the module string.
  552.  
  553.           derivation table1(1), table2(infinity);
  554.  
  555.   AXIOM
  556.      Set the axiom of the L-system. Global constants may be  used
  557.      in expressions.
  558.  
  559.   ROLL, TURN, PITCH, ANGLE, FORWARD
  560.      Set the default values for turtle commands  without  parame-
  561.      ters.   _p_i_t_c_h,  _r_o_l_l and _t_u_r_n specifies the default rotation
  562.      angle for one of the three rotation operations.  The command
  563.      _a_n_g_l_e  sets pitch and turn, roll to the same rotation angle.
  564.      The _f_o_r_w_a_r_d command specifies the default  step  for  turtle
  565.      movements.
  566.  
  567.   RANDOMIZE
  568.      Initialize the random number generator.
  569.  
  570.           randomize;         calls srand with the current time.
  571.           randomize number;  calls srand with number.
  572.  
  573.   TROPISM, WEIGHT
  574.      Set analytic tropism function (see also TROPISM  in  section
  575.      3).   The  tropism vector and the weight function may depend
  576.      on the turtle position  in  the  interpretation  process  by
  577.      using  the predefined variables _t_x, _t_y and _t_z. This can't be
  578.      done within the production rules, because the parameters  of
  579.      the  modules are determinated before the interpretation pro-
  580.      cess starts.
  581.  
  582.   EYE, LOOKAT, UP, FOV
  583.      Set viewing parameters. graphtal uses a simple model,  simi-
  584.      lar to Craig Kolbs rayshade.
  585.  
  586.   CONERES, SPHERERES
  587.      Set resolution for cone and sphere tesselation.  The  values
  588.  
  589.  
  590.  
  591.                   Last change: October 27, 1992                 9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  599.  
  600.  
  601.  
  602.      set are used by the flat and wire frame device driver.
  603.  
  604. OTHER FEATURES
  605.   COMMENTS
  606.      C-style (delimited by /*  and  */)  and  C++-style  comments
  607.      (delimited by //) are accepted at any point in the input.
  608.  
  609.   CPP
  610.      cpp (C language preprocessor) is invoked as the  first  pass
  611.      of  any  L-system  interpretation.  Therefore  you  may  add
  612.      includes, defines and macro definitions to the  input  file.
  613.      The command line option -D (see OPTIONS) attaches a value to
  614.      a name which may be used as an additional parameter  in  the
  615.      i-system description. This is useful for animations. See the
  616.      examples for further details.
  617.  
  618. SECTION 3: TURTLE COMMANDS
  619.      A lot  of  module  names  have  their  special  meaning  the
  620.      interpretation  process.  Here's the list of module bindings
  621.      in graphtal:
  622.  
  623.   BASIC MANIPULATIONS
  624.      F         Move turtle forward drawing a line (cylinder) from
  625.                start to end point.
  626.  
  627.                _F(_3) moves  turtle  forward  3  steps.  _F  move  a
  628.                default step, which is initially set to 10 but may
  629.                be redefined in the attributes  section  with  the
  630.                command _f_o_r_w_a_r_d (see ATTRIBUTES).
  631.  
  632.      f, G      Move turtle forward without drawing  a  line.  For
  633.                examples see _F.
  634.  
  635.      pt, ^     Rotate turtle around its  left  axis  in  positive
  636.                direction, i.e.  counter clock wise (pitch).
  637.  
  638.                _p_t(_4_5) or ^(_4_5)  pitches  the  turtle  45  degrees
  639.                around  it's  left  axis.  _p_t  pitches  the turtle
  640.                around it's left  axis  by  the  default  rotation
  641.                angle,  which  is initially set to 45 degrees, but
  642.                may be changed in the attributes section with  the
  643.                commands _p_i_t_c_h or _a_n_g_l_e.
  644.  
  645.      &         Pitch turtle in negative direction (clock wise).
  646.  
  647.      ro, /     Rotate turtle  around  it's  heading  in  positive
  648.                direction  (roll).  Default is 45 degrees, but may
  649.                be changed in the attributes section with the com-
  650.                mands _r_o_l_l or _a_n_g_l_e. See pitch for examples.
  651.  
  652.      \         Roll the turtle in negative direction.  For  exam-
  653.                ples see pitch.
  654.  
  655.  
  656.  
  657.                   Last change: October 27, 1992                10
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  665.  
  666.  
  667.  
  668.      tu, -     Rotate turtle around it's up direction in positive
  669.                direction  (turn).  Default is 45 degrees, but may
  670.                be changed in the attributes section with the com-
  671.                mands _t_u_r_n or _a_n_g_l_e. See pitch for examples.
  672.  
  673.      +         Turn the turtle in negative direction.  See  pitch
  674.                for examples.
  675.  
  676.      rv, $     Rotate turtle vertically, i.e. align the  turtle's
  677.                heading to a vertical position.
  678.  
  679.      |         Reverse the turtle -> tu(180).
  680.  
  681.      [         Push current turtle  state  on  the  turtle  stack
  682.                (start branch).
  683.  
  684.      ]         Set turtle state to the value  on  top  of  turtle
  685.                stack (end branch).
  686.  
  687.      wi        Set line width to new value. Default width  is  1.
  688.                The  line width command specifies the radius(!) of
  689.                the cylinder which a _F would draw.
  690.  
  691.                wi(10) -> new line width is 10 (=  radius  of  the
  692.                cylinder  to  be drawn, therefore the width of the
  693.                cylinder is 20).
  694.  
  695.      %         Cut a branch. If an % symbol is  detected  by  the
  696.                turtle  interpreter  all the following modules are
  697.                ignored until a ] (end branch) symbol. Subbranches
  698.                are deleted as well.
  699.  
  700.                G % F F [ F ] ] pt F   is interpreted as   G pt F.
  701.  
  702.   GEOMETRIC PRIMITIVES
  703.      {         Start polygon. Polygon definitions may be nested.
  704.  
  705.                { . F . tu(45) F . } generates a triangle.
  706.  
  707.      sv, .     Save current turtle position as polygon vertex.
  708.  
  709.      }         End of polygon definition.
  710.  
  711.      poly      Draw a polygon with given vertices.
  712.  
  713.                poly(0,0,0, 0,10,0, 10,10,0, 10,0,0)  generates  a
  714.                polygon with 4 vertices.
  715.  
  716.      tri       Draw a triangle with given vertices. The  first  9
  717.                parameters  are regarded as the triangle vertices,
  718.                the rest is ignored.
  719.  
  720.  
  721.  
  722.  
  723.                   Last change: October 27, 1992                11
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  731.  
  732.  
  733.  
  734.      s         Draw a  sphere  at  current  location  with  given
  735.                radius (default is 1).
  736.  
  737.                s(25) draw a sphere with radius 25 at turtle posi-
  738.                tion.
  739.  
  740.   MACROS AND LIBARY OBJECTS
  741.      graphtal supports the definition of macros  (subobject)  and
  742.      library  object  (predefined objects). These features depend
  743.      on the device driver used. Macros are supported by the  _w_i_r_e
  744.      _f_r_a_m_e  and  the _r_a_y_s_h_a_d_e device drivers. Library objects are
  745.      known to the _r_a_y_s_h_a_d_e driver. The other  device  drivers  do
  746.      not  support  these  features  and  ignore the corresponding
  747.      modules.
  748.  
  749.      sm        Start  a  macro  definition.  Macros  may  not  be
  750.                nested.  While defining a macro, all the geometric
  751.                primitives generated are collected by  the  device
  752.                driver.  This process comes to an end when the end
  753.                macro (em) command occurs in the module string.
  754.  
  755.                sm("leaf") F em
  756.                Generate a macro with the name "leaf" containing a
  757.                single cylinder object.
  758.  
  759.      em        End of macro definition. See start macro.
  760.  
  761.      xm        Execute a macro. A already defined  macro  can  be
  762.                execute  at  any  point of the interpretation pro-
  763.                cess. The  geometric  primitives  of  the  choosen
  764.                macro  are  transformed  according  to  the turtle
  765.                position and the scale factor given by the execute
  766.                macro command.
  767.  
  768.                xm("leaf")
  769.                Include the primitives of the macro "leaf" at  the
  770.                turtle location.
  771.  
  772.                xm("leaf", 0.5)
  773.                Scale the  primitives  of  the  macro  "leaf"  and
  774.                include them at the turtle location.
  775.  
  776.      lib       Include a predefined library object at the current
  777.                turtle location.  An additional scaling factor may
  778.                be specified.
  779.  
  780.                lib("apple")
  781.                Generate the library object "apple" at the current
  782.                turtle location.
  783.  
  784.                lib("apple",  1.2)  Generate  the  library  object
  785.                "apple"  at  the current turtle location and scale
  786.  
  787.  
  788.  
  789.                   Last change: October 27, 1992                12
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  797.  
  798.  
  799.  
  800.                it by 1.2.
  801.  
  802.   RENDERING ATTRIBUTES
  803.      texture   Set texture attributes for  the  following  primi-
  804.                tives.   This   feature  is  implemented  for  the
  805.                _r_a_y_s_h_a_d_e _d_r_i_v_e_r, all the  others  ignore  it.  The
  806.                implementation is very simple: the user may give a
  807.                string describing the texture to be applied.  It's
  808.                the  device driver's task to react in an appropri-
  809.                ate manner.
  810.  
  811.                texture("texture bump 0.3")
  812.                The rayshade driver adds to each following  primi-
  813.                tives the string "texture bump 0.3".
  814.  
  815.      co        Set the drawing color. All the  known  colors  are
  816.                stored  in  the file "colors.def" each line in the
  817.                format "R G B colorName". Any number of colors may
  818.                be  added  to  this  file.  The defined colors are
  819.                taken from the X11 distribution.
  820.  
  821.                co("ivory") change the color to "ivory".
  822.  
  823.   TROPISM
  824.      With tropism vectors it's possible to manipulate the  growth
  825.      of  the  L-system towards a defined direction. For example a
  826.      plant growing towards the position of the sun. If  the  tro-
  827.      pism  vector is the zero vector or the tropism weight equals
  828.      zero, then tropism calculations are disabled.
  829.  
  830.      t         Set tropism vector (see also attributes  TROPISM).
  831.                Initially tropism computations is disabled and the
  832.                tropism vector is set to (0,0,-1).
  833.  
  834.                t(1,0,0)      set  tropism  vector   to   (1,0,0).
  835.                t(1,0,0,0.5)  set  tropism  vector  to (1,0,0) and
  836.                weight factor to 0.5 ->  enable  tropism  computa-
  837.                tion.
  838.  
  839.      we        Set weight factor for  tropism  computation.  Ini-
  840.                tially  the  weight factor is set to 0.5. A factor
  841.                of 0 disables tropism calculation.
  842.  
  843.   HULLS
  844.      As explained in section 2, the turtle can react in two  dif-
  845.      ferent  ways  to a hit with a hull. The reflect behaviour is
  846.      specified through the _a_h  command,  and  the  cut  behaviour
  847.      through cb.
  848.  
  849.      ah        Activate a hull defined in the  L-system  descrip-
  850.                tion and set the reflectance factor.
  851.  
  852.  
  853.  
  854.  
  855.                   Last change: October 27, 1992                13
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  863.  
  864.  
  865.  
  866.                ah(nameOfTheHull, reflectanceFactor)
  867.                Activate the hull with the  name  "nameOfTheHull".
  868.                If  the  turtle  hits  a  hull  primitive, reflect
  869.                according to reflectanceFactor (0=no  reflectance,
  870.                1=full reflectance).
  871.  
  872.                ah("house") activate the hull "house", reflectance
  873.                factor is 1 as default.
  874.  
  875.                ah("house",  0.3)  activate  the   hull   "house",
  876.                reflectance factor is 0.3
  877.  
  878.      dh        Deactivate the hull set (if any).
  879.  
  880.      cb        Enable/disable cutting of  branches  when  a  hull
  881.                primitive is hit.
  882.  
  883.                cb or cb(1) cut  the  branch  when  hull  is  hit.
  884.                cb(0)       don't cut (default).
  885.  
  886.  
  887. SECTION 4: DEVICE DRIVERS
  888.   EXAMPLE DEVICE
  889.      The example driver produces a ASCII dump of  the  primitives
  890.      generated.  It shows the easiest way to implement a driver.
  891.  
  892.   BBOX DEVICE
  893.      The bbox driver computes the bounding box and gives  a  hint
  894.      for  the viewing parameters of the objects defined by the L-
  895.      system description.  This is useful  for  the  _f_l_a_t  _d_e_v_i_c_e,
  896.      which does no automatic view computations.
  897.  
  898.   LINE DEVICE (X11)
  899.      This driver generates a simple line drawing  of  the  object
  900.      defined  by  the  L-system.  Line  width,  color,  textures,
  901.      spheres, macros and library object are not supported by this
  902.      driver.  Viewing parameters are automatically set, when none
  903.      are provided by the user.
  904.  
  905.   WIRE DEVICE (X11)
  906.      The wire device driver draws a more realistic image  of  the
  907.      object  than line device. Not supported are colors, textures
  908.      and  library  objects.   Viewing  parameters  are  also  set
  909.      automatically, when none are provided.
  910.  
  911.   FLAT DEVICE
  912.      The flat device works with a z-buffer  algorithm,  which  is
  913.      able  to shade convex and concave polygons. Shading calcula-
  914.      tions are done with regard to the light  source  located  at
  915.      the  eyepoint.  The  driver does not depend on the number of
  916.      polygons, therefore even very large scenes  can  be  visual-
  917.      ized.  As a drawback of this feature, the viewing parameters
  918.  
  919.  
  920.  
  921.                   Last change: October 27, 1992                14
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  929.  
  930.  
  931.  
  932.      have to be provided by the user (use BBOX DEVICE  to  calcu-
  933.      late  them).  Textures and library objects are not supported
  934.      by this driver.  The output of the rendering process  is  an
  935.      image in _p_p_m _f_o_r_m_a_t (portable pixmap). There are two ways to
  936.      capture the image:
  937.  
  938.      graphtal -d flat ... -O tree.ppm tree.lsys
  939.  
  940.      graphtal -d flat ... tree.lsys > tree.ppm
  941.  
  942.   RAYSHADE DEVICE
  943.      The rayshade device is the most complete of all the drivers.
  944.      It  generates  output for the raytracer _r_a_y_s_h_a_d_e. The driver
  945.      produces at least two output files:
  946.  
  947.      graphtal -d rayshade anExample.lsys
  948.      generates the files default.ray and default.ray.def
  949.  
  950.      graphtal -d rayshade -O anExample.ray
  951.      generates the files anExample.ray and anExample.ray.def.
  952.  
  953.      The file name.ray contains the  options  for  the  rendering
  954.      process  and  in  the name.ray.def file the geometric primi-
  955.      tives are stored.  For each macro definition,  the  rayshade
  956.      driver    produces    it's    own   file   with   the   name
  957.      macrName.ray.def. If library objects are used, a  file  with
  958.      the  name  libraryName.ray.lib  must be provided by the user
  959.      for each object.
  960.  
  961.  
  962. ENVIRONMENT
  963.      With the environment variable COLORFILE  the  path  and  the
  964.      name for the color file can be specified. With
  965.  
  966.           setenv COLORFILE ~/includes/colors.def
  967.  
  968.      graphtal will read  the  color  definition  file  specified,
  969.      instead  of  the default (= colors.def in the working direc-
  970.      tory).
  971.  
  972.  
  973. AUTHOR
  974.      Christoph Streit (streit@iam.unibe.ch)
  975.  
  976.  
  977. COPYRIGHT NOTICE
  978.      Copyright (C) 1992 Christoph Streit
  979.  
  980.      All rights reserved.
  981.  
  982.      This software may be freely copied, modified, and  redistri-
  983.      buted  provided  that  this copyright notice is preserved on
  984.  
  985.  
  986.  
  987.                   Last change: October 27, 1992                15
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994. GRAPHTAL(1)              USER COMMANDS                GRAPHTAL(1)
  995.  
  996.  
  997.  
  998.      all copies.
  999.  
  1000.      You may not distribute this software, in whole or  in  part,
  1001.      as  part  of any commercial product without the express con-
  1002.      sent of the authors.
  1003.  
  1004.      There is no warranty or other guarantee of fitness  of  this
  1005.      software for any purpose.  It is provided solely "as is".
  1006.  
  1007.  
  1008. OTHER COMMENTS
  1009.      Please send bugs (accompanied by  L-systems  causing  them),
  1010.      interesting L-systems for inclusion in the release, enhance-
  1011.      ments, and suggestions to the author via email.
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.                   Last change: October 27, 1992                16
  1054.  
  1055.  
  1056.  
  1057.